\documentclass{llncs}

\usepackage{fullpage} % uses full 8.5x11 page

\renewcommand{\labelitemi}{$\bullet$}  % use normal bullets for lists

\title{Keyczar: A Cryptographic Toolkit}
\author{Arkajit Dey\inst{1} and Stephen Weis\inst{2}}

\institute{Massachusetts Institute of Technology, Cambridge, MA, USA 02139
\and
Google Inc., Mountain View, CA, USA 94043}

\begin{document}
\maketitle

\begin{abstract}
Keyczar's goal is to make it easier for application developers to safely use
cryptography. Keyczar defaults to safe algorithms, key lengths, and
modes, and prevents developers from inadvertently exposing key material. It
uses a simple, extensible key versioning system that allows developers to
easily rotate and retire keys.
\end{abstract}

\section{Introduction and Philosophy}

The motivation for Keyczar grew out of a need to make cryptography easier to
use for developers. Developers improperly using cryptography can create
serious security vulnerabilities. For instance, developers may use obsolete
algorithms, weak key lengths, improper cipher modes, or unsafely compose
cryptographic operations. Another common developer mistake is to fail to
provision for key rotation or even to hard-code keys in source code.

Keyczar's goal is to address these issues by providing a simple application
programming interface (API) for developers that handles basic cryptographic
details. Keyczar also provides a simple key versioning and management system
based on directories of human-readable flat files, which will be refered to as
\emph{keysets}. More information about Keyczar is available from {\tt
http://keyczar.org}.

\section{Using KeyczarTool}\label{keytool}

All Keyczar keys are generated with the stand-alone 
KeyczarTool utility. Two implementations of KeyczarTool are available under
{\tt org.keyczar.KeyczarTool} in Java and {\tt keyczar.keyczart} in Python.

\subsection{KeyczarTool create}
KeyczarTool must first create a new keyset using the {\tt create} command. A
newly created keyset will initially contain just a metadata file, described in
section \ref{metadata}.

{\tt KeyczarTool create} requires {\tt location} and {\tt purpose} command-line
flags that specify the location of the key set and its purpose. Valid purposes
are currently {\tt crypt} and {\tt sign}. The create command may also take
an optional {\tt name} flag to give a newly created keyset a name. If the {\tt
asymmetric} flag is specified, the newly created set will contain asymmetric
keys of the specified algorithm. Currently DSA is supported for keysets with
a sign purpose. RSA is supported for both crypting and signing keysets.

Some example {\tt create} commands:
\begin{itemize}
\item Create a symmetric signing (HMAC) keyset: \\
{\tt KeyczarTool create --location=/path/to/keyset --purpose=sign}
\item Create a symmetric crypting (AES) keyset named ``Test'': \\
{\tt KeyczarTool create --location=/path/to/keyset --purpose=crypt --name=Test}
\item Create an asymmetric signing (DSA) keyset: \\
{\tt KeyczarTool create --location=/path/to/keyset --purpose=sign
--asymmetric=dsa}
\end{itemize}

\subsection{KeyczarTool addkey}

All Keyczar keys are created using the {\tt addkey} command. This command
requires a keyset {\tt location} flag and may optionally have {\tt status},
{\tt crypter} and {\tt size} flags. Section \ref{status} describes the meaning
of the status values, but briefly they are {\it primary}, {\it active}, and {\it
inactive}. The default status is {\it active}. User-specified
key sizes are supported, although it is recommended that only default or larger
key sizes are used.

The {\tt addkey} command will create a new file in the keyset directory with an
integer version number that is one greater than the currently largest version.
Version numbers start from 1 and are described in Section \ref{versions}. For
example, if the current keyset contains the key file {\tt 1}, a new key version
will be created in the file {\tt 2}. Some example {\tt addkey} commands:
\begin{itemize}
\item Create a new primary key: \\
{\tt KeyczarTool addkey --location=/path/to/keyset --status=primary}
\item Create a new active key: \\
{\tt KeyczarTool addkey --location=/path/to/keyset} 
\end{itemize}

Keyczar supports encrypted keysets. The {\tt crypter} flag may be used to
encrypt a key set when adding a new key. It will specify the location of an
existing keyset which will be used to encrypt a newly generated key: 
 
\begin{itemize}
\item Create a new active key and encrypt it with another keyset: \\
{\tt KeyczarTool addkey --location=/path/to/keyset
--crypter=/path/to/crypting/keys}
\end{itemize}

\subsection{KeyczarTool pubkey}

Public keys in Keyczar are exported from existing asymmetric key sets. The
{\tt pubkey} command requires both an existing {\tt location} flag and a {\tt
destination} where public keys will be exported. If the keyset under {\tt
location} was not created with an {\tt asymmetric} flag, then a {\tt pubkey}
command will fail. An example {\tt pubkey} command works as follows: \\
{\tt KeyczarTool pubkey --location=/path/to/keyset --destination=/path/to/dest}

\subsection{KeyczarTool promote, demote, and revoke}

The {\tt promote}, {\tt demote}, and {\tt revoke} commands are used to change
key status values. Each of these commands require a {\tt location} and {\tt
version} flag. 

Promoting an {\it active} key will raise its status to
{\it primary}, and promoting an {\it inactive} status will make
it {\it primary}. There can only be a single {\it primary} key in a given key
set. 

Similarly, {\tt demote} will lower a {\it primary} key to {\it active},
and an {\it active} key to {\it inactive}. The {\tt revoke}
command will only work for {\it inactive} status values.
The {\tt revoke} command will permenantly delete key material, so should be
used with caution.

Some example {\tt promote}, {\tt demote}, and {\tt revoke} commands. Suppose
that key version 1 initially has an {\it active} status:
\begin{itemize}
\item Promote {\it active} version 1 to {\it primary}: \\
{\tt KeyczarTool promote --location=/path/to/keyset --version=1}
\item Demote {\it primary} version 1 back to {\it active}: \\
{\tt KeyczarTool demote --location=/path/to/keyset --version=1}
\item Demote {\it active} version 1 to {\it inactive}: \\
{\tt KeyczarTool demote --location=/path/to/keyset --version=1}
\item Revoke the {\it inactive} version 1: \\
{\tt KeyczarTool revoke --location=/path/to/keyset --version=1}
\end{itemize}

\section{Using Java Keyczar}

The {\tt org.keyczar} package contains four public classes that
developers will use for cryptographic functions: {\tt Crypter}, {\tt
Encrypter}, {\tt Signer}, and {\tt Verifier}. All four classes are children
of the abstract {\tt Keyczar} class and may be constructed either with a {\tt
KeyczarReader} or a simple String location of a keyset:
\begin{itemize}
  \item Constructor: {\tt Keyczar(KeyczarReader reader)}
  \item Constructor: {\tt Keyczar(String keySetLocation)}
\end{itemize} 

\subsection{KeyczarReaders}

The {\tt KeyczarReader} interface may be implemented by any class that reads
key material from a keyset. Keyczar includes a {\tt KeyczarFileReader} class
that is used by the {\tt Keyczar(String keySetLocation)} constructor to read
files from the local disk. Developers may implement their own {\tt
KeyczarReaders} to read from arbitrary sources and pass them to {\tt
Keyczar} constructors.

\subsection{Encrypters}

The {\tt Encypter} class is only able to encrypt data. {\tt Encrypter} objects
will be initialized by passing it the location of a crypting key set.
{\tt Encrypters} can encrypt plaintext encoded in UTF-8 Strings, byte arrays, or
ByteBuffers. {\tt Encrypters} must be initialized with a keyset containing a
{\it primary} status key to encrypt any data.
\begin{itemize}
  \item {\tt String encrypt(String input)}: Encrypt a string and return a
  WebSafeBase64 output ciphertext.
  \item {\tt byte[] encrypt(byte[] input)}: Encrypt a byte array and return the
  ciphertext as a byte array.
  \item {\tt int encrypt(ByteBuffer input, ByteBuffer output)}: Encrypt the
  contents of the input buffer and write the ciphertext to the output. Return
  the number of bytes written.
\end{itemize}

\subsection{Crypters}

The {\tt Crypter} class is a child of {\tt Encrypter} and is also able to
decrypt data. {\tt Crypter} objects may only be initialized by crypting key sets
that contain keys able to decrypt, namely symmetric keys or private keys. {\tt
Crypters} cannot be initialized with public keys. {\tt Crypters} can decrypt
ciphertext in WebSafeBase64 encoded Strings, byte arrays, or ByteBuffers.
\begin{itemize}
  \item {\tt String decrypt(String input)}: Decrypt a WebSafeBase64 string and
  return a UTF-8 encoded plaintext output.
  \item {\tt byte[] decrypt(byte[] input)}: Decrypt a ciphertext byte array and
  return the plaintext as a byte array.
  \item {\tt int decrypt(ByteBuffer input, ByteBuffer output)}: Decrypt the
  input ByteBuffer and write its output into the given output ByteBuffer.
  Return the number of bytes written.
\end{itemize}

\subsection{Verifiers}

The {\tt Verifier} class is only able to verify signatures. {\tt Verifier}
objects may be initialized by passing it the location of any signing key set.
It can verify signatures in WebSafeBase64 format, as byte arrays, or in
ByteBuffers:
\begin{itemize}
  \item {\tt boolean verify(String data, String signature)}: Verifies a
  WebSafeBase64 encoded signature on the given UTF-8 String of data. Returns a
  boolean representing whether the signature is valid.
  \item {\tt boolean verify(byte[] data, byte[] signature)}: Verifies a
  signature in a byte array on the given byte array of data. Returns a
  boolean representing whether the signature is valid. 
  \item {\tt boolean verify(ByteBuffer data, ByteBuffer signature}: Verifies a
  signauture in a ByteBuffer on the given ByteBuffer of data. Returns a boolean
  representing whether the signature is valid.
\end{itemize}

\subsection{Signers}

The {\tt Signer} class is a child of the {\tt Verifier} class and is also able
to generate signatures by signing data. {\tt Signer} objects may only be
initialized by keysets that are able to sign, namely symmetric keys and private
keys. {\tt Signers} may not be initialized by public keys and may sign data in
UTF-8 Strings, byte arrays, or ByteBuffers. {\tt Signers} must be initialized
with a keyset containing a {\it primary} status key to sign any data.
\begin{itemize}
  \item {\tt String sign(String data)}: Signs a UTF-8 string of data and
  returns a signatures as a WebSafeBase64 string.
  \item {\tt byte[] sign(byte[] data)}: Signs a byte array of data and returns
  a signature in a byte array.
  \item {\tt int sign(ByteBuffer data, ByteBuffer signature}: Signs a
  ByteBuffer of input and writes the signature to the output ByteBuffer.
  Returns the number of bytes written.
\end{itemize}

\subsection{Example: Putting KeyczarTool and Java Keyczar Together}

The following command-line commands would create a new AES encrypting key:
\begin{verbatim}
KeyczarTool create --location=/aeskeys --purpose=crypt
KeyczarTool addkey --location=/aeskeys --status=primary
\end{verbatim}

Then within a Java program, the following code would encrypt a string of data:
\begin{verbatim}
Crypter crypter = new Crypter(``/aeskeys'');
String ciphertext = crypter.encrypt(``Some data to encrypt'');
\end{verbatim}

This same ciphertext would be decrypted with a call to {\tt Crypter.decrypt()}:
\begin{verbatim}
String plaintext = crypter.decrypt(ciphertext);
\end{verbatim}

Using public keys is similar:
\begin{verbatim}
KeyczarTool create --location=/rsakeys --purpose=crypt --asymmetric
KeyczarTool addkey --location=/rsakeys --status=primary
KeyczarTool pubkey --location=/rsakeys --destination=/rsa-publickeys
\end{verbatim}

Then in Java, we can encrypt using the public key set, but need the private key
set to decrypt:
\begin{verbatim}
// Initialize an Encrypter with the public keys
Encypter encrypter = new Encrypter(``/rsa-publickeykeys'');
String ciphertext = encrypter.encrypt(``Some data to encrypt'');
... 
// Initialize a Crypter with the private keys
Crypter crypter = new Crypter(``/rsakeys'');
String plaintext = crypter.decrypt(ciphertext);
\end{verbatim}

Signing and verifying is similarily easy:
\begin{verbatim}
KeyczarTool create --location=/hmackeys --purpose=sign
KeyczarTool addkey --location=/hmackeys --status=primary
\end{verbatim}

In Java:
\begin{verbatim}
Signer signer = new Signer(``/hmackeys'');
String signature = signer.sign(``Some data to sign'');
boolean verified = signer.verify(``Some data to sign'', signature);
\end{verbatim}

See Section \ref{walkthrough} for a more detailed walkthrough and sample test
vectors.

\section{Using Python Keyczar}

The API for Python is very similar to the one for Java. The same four classes,
{\tt Crypter}, {\tt Encrypter}, {\tt Signer}, and {\tt Verifier} are in the
{\tt keyczar.keyczar} module and descend from the abstract {\tt Keyczar} class.
They have the same use as their corresponding classes in Java. As in Java, they
can constructed from a {\tt Reader} or from a string location of a keyset. The
methods of construction are slightly different:

\begin{itemize}
  \item Constructor: {\tt Keyczar(reader)}
  \item Static Method: \verb|Keyczar.Read(key_set_location)|
\end{itemize}

\subsection{Readers}

The abstract class {\tt Reader} can be extended by any class that reads key
material from a keyset. Python Keyczar supplies a {\tt FileReader}
implementation that is used by the {Keyczar.Read} static method to read key
files from local disk. Just as in Java, developers can create their own
{\tt Readers} by extending from the base class.

\subsection{Differences from Java Keyczar}

The main four public classes don't treat strings, byte arrays, or btye
buffers differently. The just deal in strings which can either be UTF-8 or
byte strings. And the output is also always a WebSafeBase64 string, not a byte
array.
\begin{itemize}
  \item {\tt Encrypter.Encrypt: data (string) -> ciphertext (Base64 string)}
  \item {\tt Crypter.Decrypt: ciphertext (Base64 string) -> data (string)}
  \item {\tt Signer.Sign: data (string) -> sig (Base64 string)}
  \item {\tt Verifier.Verify: data (string), sig (Base64 string) -> boolean}
\end{itemize}

\section{Keys}

\subsection{Statuses}\label{status}

As described in Section \ref{keytool}, Keyczar keys may have one of three
status values: {\it primary}, {\it active}, {\it inactive}.
Keys with a primary status value are used to generate new cryptomaterial, that
is, signatures or ciphertexts. Keys of all status values may be used to verify
or decrypt legacy data, but are not used to generate new data.

The idea is that a key will start its life as a primary key and be used to
generate cryptographic output. That key can be rotated by generating a new
primary key value, and changing the existing primary key to be active. Active
keys will be kept around to verify and decrypt existing data, until they are
inactive. A key that is inactive is identical
to an active key, except its usage statistics are collected by default. When a
key that is inactive is no longer used, it can be safely
revoked and removed from a key set entirely.

\subsection{Key Metadata}\label{metadata}

Each Keyczar keyset contains a metadata file that contains information about
that set's name, purpose, key type, encrypted status, and a list of key version
information (see Section \ref{versions}). Valid purposes are encrypting, 
verifying, encrypting and decrypting, and signing and verifying. Having the
purpose value in the metadata prevents a key from being used for an 
inappropriate purpose. For example, an RSA key that is typically used for
encrypting shouldn't also be used for signing.

These purposes correspond to their respective public and symmetric/private
keys, and are usable by the Keyczar classes specified in the table below: 

\vspace*{3mm}
\begin{tabular}{ l | l | l }
{\bf Purpose} &  {\bf Public, Private, or Symmetric } & {\bf Class used by} \\
\hline Encrypting & Public & Encrypter or Crypter \\ \hline
Encrypting and Decrypting & Private or Symmetric & Crypter \\ \hline
Verifying & Public & Verifier or Signer \\ \hline 
Verifying and Signing & Private or Symmetric & Signer \\ \hline
\end{tabular}
\vspace*{3mm}

Each metadata file contains a specific key type which is the only type of key
that set can contain. Currently, the valid key types are AES, HMAC-SHA1, DSA
Private, DSA Public, RSA Private, and RSA Public.

It also contains a boolean flag indicating whether the key files are stored in
encrypted format.

The metadata will contain a list of version information, which is
described in Section \ref{versions}. See Section \ref{walkthrough} for a sample
JSON metadata file.

\subsection{Versions}\label{versions}

Each key metadata (see Section \ref{metadata}) contains a list of version
numbers corresponding to the keys contained in a given keyset. Each version
specifies an integral version number, a status of either {\it active}, {\it
primary}, or {\it inactive}, and a boolean specifying whether
the key is exportable outside of Keyczar.

By default, key version numbers start from 1 and increase monotonically.
However, key version numbers may be any positive, non-zero integral values.

\subsection{Output Headers} \label{header}

Each Keyczar output is tagged with a Keyczar-specific header. The header format
is as follows:

\vspace*{3mm}
\begin{tabular}{| l | l |}
\hline
Format & Key Hash \\ \hline
1 byte & 4 bytes \\ \hline
\end{tabular}
\vspace*{3mm}

See Section \ref{walkthrough} for a concrete example of an output header.

\subsubsection{Version Byte}

The first byte of all output is a single byte representing the version of
keyczar that generated it. The current version byte is 1. All other values are
reserved.

\subsubsection{Key hash}\label{keyhash}

Each header includes 4-byte truncated SHA-1 hash of the raw key
material itself. The following values will be hashed for each key type:
\begin{itemize}
  \item HMAC: 4-byte integer value representing the length of the HMAC key in
  bytes, followed by the actual HMAC key bytes.
  \item AES: 4-byte integer value representing the length of the AES key,
  followed by the acutal AES key bytes, followed by the 4-byte KeyHash of the
  attached HMAC key.
  \item DSA Public: 4-byte integer value representing the length of the X.509
  representation of this key, followed by the X.509 representation.
  \item DSA Private: Same as DSA Public.
  \item RSA Public: 4-byte integer value representing the length of the X.509
  representation of this key, followed by the X.509 representation.
  \item RSA Private: Same as RSA Public. 
\end{itemize}

The SHA-1 output on each of these values is truncated to the first four bytes.
For example: The truncated 4-byte truncated SHA-1 values:
\begin{enumerate}
  \item The 4-byte truncated hash of SHA-1("") = {\tt da39a3ee 5e6b4b0d 3255bfef
  95601890 afd80709} encoded in hexadecimal is {\tt da39a3ee.}
  \item The truncated hash of SHA-1("The quick brown fox jumps over the lazy
  dog") = {\tt 2fd4e1c6 7a2d28fc ed849ee1 bb76e739 1b93eb12} is
  {\tt 2fd4e1c6 }.
\end{enumerate}

\subsection{Key Formats}\label{formats}

All key files are kept in JSON format and have a ``size'' field indicating the
length of the key in bits. Additional fields are described below for each key
type.

\subsubsection{HMAC}

HMAC keys also have the additional ``hmacKeyString'' field which is a Base64
representation of the raw HMAC key bytes.

\subsubsection{AES}

AES keys have an ``aesKeyString'' field which is a Base64 representation of the
raw AES key bytes. They also have an attached HMAC key, which is kept in a
``hmacKey'' field. There is an additional ``mode'' field which currently only
supports ``CBC''.

\subsubsection{Public RSA}

Public RSA keys have an ``x509'' field containing the Base64 representation of
a X.509 public key certificate. 

\subsubsection{Private RSA}

Private RSA keys contain a public RSA key, and a ``pkcs8'' field containing a
Base64 representation of a PKCS8 encoded RSA private key. 

\subsubsection{Public DSA}

Public DSA keys have an ``x509'' field containing the Base64 representation of
a X.509 public key certificate. 

\subsubsection{Private DSA}

Private DSA keys contain a public DSA key, and a ``pkcs8'' field containing a
Base64 representation of a PKCS8 encoded DSA private key. 

\section{Output Formats}

\subsection{Signatures}\label{signatures}

A Keyczar signature consists of a header (described in Section \ref{header})
followed by a algorithm-dependent signature:

\vspace*{3mm}
\begin{tabular}{| c | c |}
\hline
Header & Sign(header $|$ M) \\
\hline 5 bytes & Algorithm-dependent length \\ \hline
\end{tabular}
\vspace*{3mm}

(Note: $|$ represents string concatenation.)

\vspace*{3mm}

For example, HMAC keys will produce a 20-byte output, so have the form:

\vspace*{3mm}
\begin{tabular}{| c | c |}
\hline
Header & HMAC-SHA1(header $|$ M) \\ \hline
5 bytes & 20 bytes \\ \hline
\end{tabular}
\vspace*{3mm}
\subsection{Ciphertext}

A Keyczar ciphertext contains a header (described in Section \ref{header}), an
IV (if needed), the algorithm-dependent ciphertext, and a signature on the
preceding fields (for symmetric keys only):

\vspace*{3mm}
\begin{tabular}{| c | c | c | c |}
\hline
Header & IV (if any) & Encrypt(M) & Sign(header $|$ IV $|$ M) (if any) \\ \hline
5 bytes & Algorithm-dependent & Algorithm-dependent & Algorithm-dependent \\
\hline
\end{tabular}
\vspace*{3mm}

For example, 128-bit AES keys (which have an attached HMAC key) used in CBC
mode would produce the following output:

\vspace*{3mm}
\begin{tabular}{| c | c | c | c |}
\hline
Header & IV & AES-CBC(M) & HMAC-SHA1(header $|$ IV $|$ M) \\ \hline
5 bytes & 16 bytes & Algorithm-dependent & 20 bytes \\
\hline
\end{tabular}
\vspace*{3mm}

In contrast, RSA ciphertexts neither use IVs nor are signed. Thus, the RSA
ciphertext format is:

\vspace*{3mm}
\begin{tabular}{| c | c | c | c |}
\hline
Header & RSA-OAEP(M)  \\ \hline
5 bytes & Single RSA block  \\
\hline
\end{tabular}
\vspace*{3mm}

\section{Algorithm Details}

These are the default key lengths, algorithms, and padding modes used:

\begin{itemize}
  \item HMAC: Default keys are 256 bits. SHA1 used as the hash
  algorithm.
  \item AES: Default keys are 128 bits. 192 and 256 bit keys are also supported.
  CBC mode with PKCS\#5 padding is used by default.
  \item DSA: DSA-SHA1 signing algorithm used by default. Default key size is
  1024 bits.
  \item RSA Encryption: RSA-OAEP encryption is used. Default key size is 2048
  bits. 1024, 768, and 512 bit keys are also supported.
  \item RSA Signatures: RSA-SHA1 signing is used. Default key size is 2048
  bits. 1024, 768, and 512 bit keys are also supported.
\end{itemize}


\section{Walkthrough and Sample Data}\label{walkthrough}

\subsection{Creating an HMAC Keyset}
A {\tt meta} file is created by a call to the {\tt KeyczarTool create} command.
The following example was created using the command: \\
{\tt KeyczarTool create --location=/path/to/keyset --name=test --purpose=sign}

\begin{verbatim}
{
 "name":"test",
 "purpose":"SIGN_AND_VERIFY",
 "type":"HMAC_SHA1",
 "versions":[],
 "encrypted":false
}
\end{verbatim}

\subsection{Generating a HMAC key}

The following command will create a new key in an existing keyset: \\
{\tt KeyczarTool addkey --location=/path/to/keyset}

This will add key version information to the existing {\tt meta} file: 
\begin{verbatim}
{
 "name":"test",
 "purpose":"SIGN_AND_VERIFY",
 "type":"HMAC_SHA1",
 "versions":[
    { "exportable":false,
      "status":"ACTIVE",
      "versionNumber":1}
    ],
 "encrypted":false
}
\end{verbatim}

It will also create a key version file named ``1'':
\begin{verbatim}
{
 "hmacKeyString":"9E7yslYyE4GHzq2WbppOOjGqBL7OGXxy5OsFSqBn2ao",
 "size":256
}
\end{verbatim}

\subsection{Promoting a Key}
Since no status was specified, key version 1 was created with an ``active''
status. That means it can be used for verifying signatures, but not generating
new signatures. Since we just created this key, there are no existing
signatures to verify. We have to promote it to a ``primary'' status before
it's useful: \\
{\tt KeyczarTool promote --location=/path/to/keyset --version=1}

This will just alter the meta file to reflect the promotion:
\begin{verbatim}
{
 "name":"test",
 "purpose":"SIGN_AND_VERIFY",
 "type":"HMAC_SHA1",
 "versions":[
    { 
      "exportable":false,
      "status":"PRIMARY",
      "versionNumber":1
    }
  ],
 "encrypted":false
}
\end{verbatim}

We can generate a second key version with a primary status as follows: \\
{\tt KeyczarTool addkey --location=/path/to/keyset --status=primary}

This create a new key version ``2'' with a primary status. Keysets can only have
one primary key at a time, so this automatically demotes key version ``1'' to
be active:
\begin{verbatim}
{
 "name":"test",
 "purpose":"SIGN_AND_VERIFY",
 "type":"HMAC_SHA1",
 "versions":[
    { 
      "exportable":false,
      "status":"ACTIVE",
      "versionNumber":1
    },
    { 
      "exportable":false,
      "status":"PRIMARY",
      "versionNumber":2
    }
  ],
 "encrypted":false
}
\end{verbatim}

This creates another key version file ``2'' with the following contents:
\begin{verbatim}
{
  "hmacKeyString":"-jkgTURAPoBr9SaQ5NLsFq2Xu5Z54RmnHYHlv1RVE7s",
  "size":256
}
\end{verbatim}

\subsection{Key Hash Values}

Note that the Base64 value of the ``hmacKeyString'' in the previous
section decodes to the following 32 bytes in hexadecimal format:
\begin{verbatim}
fa, 39, 20, 4d, 44, 40, 3e, 80,
6b, f5, 26, 90, e4, d2, ec, 16,
ad, 97, bb, 96, 79, e1, 19, a7,
1d, 81, e5, bf, 54, 55, 13, bb
\end{verbatim}

These key bytes will be hashed to obtain a key identifier. The raw key bytes
will be prefixed by a byte representation of the length in bytes. In this case,
the length is 32, so the following bytes (in hexadecimal format) will be
hashed with SHA-1:\\ {\tt  SHA-1(00, 00, 00, 20, fa, 39, \ldots, 13, bb)}

This produces the following 20-byte SHA1 output:
\begin{verbatim}
d8, 36, 36, 62, d0, 6d, cb, a7,
35, cd, 6c, 69, 33, 40, df, 87,
ce, da, d9, 8d
\end{verbatim}

This is truncated down to the four bytes {\tt d8, 36, 36, 62}, which is
this key's hash identifier. As described in Section \ref{header}, all output
will be prefixed with a version byte (currently equal to 1) and this identifier.

\subsection{Signing and Verifying} 

To sign the string ``Hello world'' with our newly generated keys in Java, we
would simply use the following two lines of code.

\begin{verbatim}
Signer signer = new Signer("/path/to/keyset"); 
String signature = signer.sign("Hello world");
\end{verbatim}

Keyczar will convert the string to the bytes to the following values:
\begin{verbatim}
48, 65, 6c, 6c, 6f, 20, 77, 6f, 72, 6c, 64
\end{verbatim} 

The output Base64 encoded signature would be the value {\tt
Adg2NmIPTshpioGdunRaGRYWFNgheKmjvg}, which corresponds to the bytes:
\begin{verbatim}
1, d8, 36, 36, 62, f, 4e, c8,
69, 8a, 81, 9d, ba, 74, 5a, 19,
16, 16, 14, d8, 21, 78, a9, a3,
be,
\end{verbatim}

Note that the first output byte is the version byte 1, followed by the 4-byte
key hash identifier, and a 20-byte HMAC-SHA1 output. All signatures produced by
this key will have this same identifier. Verification of this signature is
simple:
\begin{verbatim}
boolean isValid =
    signer.verify("Hello world", "Adg2NmIPTshpioGdunRaGRYWFNgheKmjvg");
\end{verbatim}

\section{Licenses and Dependencies}

Keyczar is available under an Apache 2.0 license \cite{apache2}. Java Keyczar
depends on the Google GSON package \cite{google-gson}. It also relies on the
Java's {\tt javax.crypto} package, which may not be available in all countries
due to local laws and regulations.

Python Keyczar depends on the Python Cryptography Toolkit \cite{python-crypto}
and simplejson \cite{simplejson}. 

\section{Acknowledgements}

Thanks to Ben Laurie, Marius Schilder, and Neil Daswani for their original
design contributions. Thanks to Sarvar Patel, Loren Kornfelder, Manuel Marquez
Garrido, and Laura Krotowski for their various contributions.

\bibliography{keyczar}
\bibliographystyle{acm}

\end{document}
